Crate winresult

Expand description

🦀 winresult - windows result codes 🦀

Debug-friendly types for windows result codes.

Why?

u32 error codes are annoying to dbg!(...). winresult has awesome Debug impls.
u32 error codes are annoying to view in your debugger. winresult has awesome *.natvis files. Use natvis-pdbs!
typoing ERROR_WHATEVER in a match is a mere warning. ERROR::WHATEVER is a hard error.
(I’d still use #![deny(unreachable_patterns)] anyways.)
ERROR_INVALID_FUNCTION == S_FALSE (== 1.) Lame!

ERROR_FILE_NOT_FOUND (2) is a mess. A function or GetLastError might return:

label	value	notes
`ERROR_FILE_NOT_FOUND`	`0x00000002`	Not an `HRESULT` (would be “successful”)
`HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)`	`0x80070002`	hresult.info “incorrectly” labels `ERROR_*` as this
`D3D10_ERROR_FILE_NOT_FOUND`	`0x88790002`	Different facility, same code
`D3D11_ERROR_FILE_NOT_FOUND`	`0x887C0002`	Different facility, same code

ERROR_* is a mixture of HRESULTs and non-HRESULTs. Can you keep them straight? No. No you cannot. Stop lying.

Types

min	max	type	notes
0	0xFFFF	`ErrorCode`
0	0x7FFFFFFF	`HResultSuccess`
0x80000000	0xFFFFFFFF	`HResultError`
0	0xFFFFFFFF	`HResult`	`HResultSuccess` \| `HResultError`
0	0xFFF	`HResultFacilityMicrosoft`
0	0xFFFFFFFF	`NtStatus`	~~`SuccessNtStatus` \| `ErrorNtStatus`~~
0	0xFFF	`NtStatusFacilityMicrosoft`
0	4	`NtStatusSeverity`
0	0xFFFFFFFF	`WaitCode`	mostly <= 0x102
0	0xFFFFFFFF	`ErrorHResultOrCode`	`ErrorCode` \| `HResultError`

Modules of Note

mod	types
ERROR	ErrorCode, HResultError, and HResultSuccess(!)
FACILITY	HResultFacilityMicrosoft, NtStatusFacilityMicrosoft
STATUS	NtStatus
STATUS::SEVERITY	NtStatusSeverity
WAIT	WaitCode

Buggy Bitwise Comparisons to Forbid

left	right	why
`ErrorCode`	`HResultError`	never `true`, non-overlapping ranges, need to add or remove facility
`ErrorCode`	`HResultSuccess`	`ERROR_INVALID_FUNCTION == S_FALSE`, need to add or remove facility
`ErrorCode`	`HResult`	`ERROR_INVALID_FUNCTION == S_FALSE`, need to add or remove facility
`ErrorCode`	`WaitCode`	`ERROR_INVALID_FUNCTION == WAIT_OBJECT_0+1`
*Success	Error	never `true` except by accident

Conversions

HResultSuccess → HResult
(HResultFacilityMicrosoft, ErrorCode) → HResultError → HResult

Modules

WinRT / UWP AppModel

APPX package

Background Task

Remote Desktop Protocol Bitmap Cache?

CAT

COM Categories

CERT

Certificates (for e.g. HTTPS etc.)

CERTSRV

Certificate Server (for e.g. Certificate Authority validation, etc.)

COM Class

Clipboard

COM

COM+ Queued Components Protocol

Direct3D 10+

Direct3D Errors

D3DX Errors

D3DX .X file type errors

DATA

OLE / Clipboard Stuff?

Digital Signature

Domain Name Services

OLE / Data Values / Clipboard Stuff?

DWM

Display Window Manager (desktop rendering composition)

DirectX

Errors Codes. Typically HResultErrors.

EAS

Exchange ActiveSync

ERROR

Error Codes. Mostly a mixture of HResultErrors and ErrorCodes. submodules: CLOUD_FILE, CLUSTER, DBG, DS, EVT, GRAPHICS, IPSEC, MRM, MUI, NDIS, PRI_MERGE, SECUREBOOT, SERVICE, SVHDX, SXS, SXS::XML, VHD, WMI
Note that ERROR::SUBCATEGORY::CODE is also generally exported as ERROR::SUBCATEGORY_CODE, although the latter is hidden from the docs to reduce clutter.

FACILITY_* Values for HResults and NtStatuses.
pub mod FACILITY::HRESULT::*, FACILITY::NTSTATUS::*;

FVE

Full Volume Encryption / Bitlocker

FWP

Windows Filtering Platform

GCN

Host Computer Network

HCN